android.ndk.sync source code

1 /*
2  *  Copyright 2017 The Android Open Source Project
3  *
4  *  Licensed under the Apache License, Version 2.0 (the "License");
5  *  you may not use this file except in compliance with the License.
6  *  You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  *  Unless required by applicable law or agreed to in writing, software
11  *  distributed under the License is distributed on an "AS IS" BASIS,
12  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  *  See the License for the specific language governing permissions and
14  *  limitations under the License.
15  */
16 
17 /**
18  * @addtogroup Sync
19  * @{
20  */
21 
22 /**
23  * @file sync.h
24  */
25 
26 module android.ndk.sync;
27 
28 import arsd.jni;
29 import android.ndk;
30 
31 struct sync_file_info_ {}
32 struct sync_fence_info {}
33 
34 extern (C):
35 nothrow:
36 @nogc:
37 
38 /* Fences indicate the status of an asynchronous task. They are initially
39  * in unsignaled state (0), and make a one-time transition to either signaled
40  * (1) or error (< 0) state. A sync file is a collection of one or more fences;
41  * the sync file's status is error if any of its fences are in error state,
42  * signaled if all of the child fences are signaled, or unsignaled otherwise.
43  *
44  * Sync files are created by various device APIs in response to submitting
45  * tasks to the device. Standard file descriptor lifetime syscalls like dup()
46  * and close() are used to manage sync file lifetime.
47  *
48  * The poll(), ppoll(), or select() syscalls can be used to wait for the sync
49  * file to change status, or (with a timeout of zero) to check its status.
50  *
51  * The functions below provide a few additional sync-specific operations.
52  */
53 
54 /**
55  * Merge two sync files.
56  *
57  * This produces a new sync file with the given name which has the union of the
58  * two original sync file's fences; redundant fences may be removed.
59  *
60  * If one of the input sync files is signaled or invalid, then this function
61  * may behave like dup(): the new file descriptor refers to the valid/unsignaled
62  * sync file with its original name, rather than a new sync file.
63  *
64  * The original fences remain valid, and the caller is responsible for closing
65  * them.
66  *
67  * Available since API level 26.
68  */
69 int sync_merge (const(char)* name, int fd1, int fd2);
70 
71 /**
72  * Retrieve detailed information about a sync file and its fences.
73  *
74  * The returned sync_file_info must be freed by calling sync_file_info_free().
75  *
76  * Available since API level 26.
77  */
78 sync_file_info_* sync_file_info (int fd);
79 
80 /**
81  * Get the array of fence infos from the sync file's info.
82  *
83  * The returned array is owned by the parent sync file info, and has
84  * info->num_fences entries.
85  *
86  * Available since API level 26.
87  */
88 
89 // This header should compile in C, but some C++ projects enable
90 // warnings-as-error for C-style casts.
91 sync_fence_info* sync_get_fence_info (const(sync_file_info_)* info);
92 
93 /**
94  * Free a struct sync_file_info structure
95  *
96  * Available since API level 26.
97  */
98 void sync_file_info_free (sync_file_info_* info);
99 
100 /* __ANDROID_API__ >= 26 */
101 
102 /* ANDROID_SYNC_H */
103 
104 /** @} */